Determines the item number of an item at a particular location in a dialog box.

DialogItemIndexZeroBased FindDialogItem (
    DialogPtr theDialog, 
    Point thePt
);

theDialog

A pointer to a dialog structure.

thePt

The point (in local coordinates) where the mouse-down event occurred.

function result

When an embedding hierarchy is established, the FindDialogItem function returns the deepest control selected by the user corresponding to the point specified in the thePt parameter. When an embedding hierarchy does not exist, FindDialogItem performs a linear search of the item list resource and returns a number corresponding to the hit item’s position in the item list resource. For example, it returns 0 for the first item in the item list, 1 for the second, and 2 for the third. If the mouse is not over a dialog item, FindDialogItem returns –1.

DISCUSSION

The function FindDialogItem is useful for changing the cursor when the user moves the cursor over a particular item.

To get the proper item number before calling the GetDialogItem function or the SetDialogItem function, add 1 to the result of FindDialogItem, as shown here:

theItem = FindDialogItem(theDialog, thePoint) + 1;

Note that FindDialogItem returns the item number of disabled items as well as enabled items.

VERSION NOTES

This function was changed with Appearance Manager 1.0 to support embedding hierarchies.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.

© 2000 Apple Computer, Inc. — (Last Updated 4/14/2000)